---
layout: docs
page_title: Domain Model - Credential Stores
description: |-
  The anatomy of a Boundary credential store
---

# Credential Stores

A credential store is a resource
that can retrieve, store, and potentially generate [credentials][]
of differing types and differing access levels.
It belongs to a [project][] and supports the
[principle of least privilege](https://en.wikipedia.org/wiki/Principle_of_least_privilege)
by providing mechanisms to limit the [credentials][] it can access
to the minimum necessary for the project it is in.
A credential store can also contain [credential libraries][].

## Attributes

A credential store has the following configurable attributes:

- `name` - (optional)
  If set, the `name` must be unique within the credential store's [project][].

- `description` - (optional)

### Vault Credential Store Attributes

A Vault credential store has the following additional attributes:

- `address` - (required)
  The address of the Vault server.
  This should be a complete URL such as `https://127.0.0.1:8200`.

- `token` - (required)
  A token used for accessing Vault.
  This token must meet the [Vault token requirements][token_requirements] described below.
  Each Vault credential store must be configured with a unique Vault token.

- `ca_cert` - (optional)
  A PEM-encoded CA certificate to verify the Vault server's TLS certificate.

- `tls_server_name` - (optional)
  Name to use as the SNI host when connecting to Vault via TLS.

- `tls_skip_verify` - (optional)
  Disable verification of TLS certificates.
  Using this option is highly discouraged as it decreases the security of data
  transmissions to and from the Vault server.

- `client_certificate` - (optional)
  A PEM-encoded client certificate to use for TLS authentication to the Vault server.

- `client_certificate_key` - (optional)
  A PEM-encoded private key matching the client certificate from `client_certificate`.

- `namespace` - (optional)
  A Vault [namespace][]. Requires Vault Enterprise.

- `worker_filter` <sup>HCP Only</sup> - (optional)
  A [filter] used to control which [PKI workers] can handle Vault requests.
  This allows the use of private Vault instances with Boundary. PKI workers
  deployed in the same network as a private Vault instance can access and relay
  Vault requests to Boundary controllers.
  ~> **Note:** A PKI worker that matches the worker filter must exist before defining the Vault credential store, as it
  will perform the Vault calls needed to set up the credential store with Boundary.

### Static Credential Store Attributes

A static credential store has no type-specific attributes.

## Referenced By

- [Credential Library][]
- [Credential][]
- [Project][]

## Service API Docs

The following services are relevant to this resource:

- [Credential Store Service](/boundary/api-docs/credential-store-service)

[credential library]: /boundary/docs/concepts/domain-model/credential-libraries
[credential libraries]: /boundary/docs/concepts/domain-model/credential-libraries
[credential]: /boundary/docs/concepts/domain-model/credentials
[credentials]: /boundary/docs/concepts/domain-model/credentials
[project]: /boundary/docs/concepts/domain-model/scopes#projects

## Vault Token Requirements

Each Vault credential store must be configured with a unique Vault token.
The Vault tokens for all credential stores
must be [periodic][], [renewable][], and an [orphan][].
All tokens must also have the capabilities of the
[Vault Boundary Controller Policy][token_policy] described below.

### Vault Policies

The credential store's token must have the capabilities to issue credentials for
each of it's [credential libraries][] plus the capabilities of the
[Vault Boundary Controller Policy][token_policy] described below.

We recommend creating a unique Vault policy for each Vault credential store that
grants the minimum set of permissions needed by the credential store's
libraries. We also recommend the [Vault Boundary Controller
Policy][token_policy] be kept distinct from any other Vault policies. This
allows each credential store to have a token that is configured with two
polices: one shared by all credential stores and one unique to that credential
store. This also allows a credential store to be created with the minimum
permissions necessary at any point in time. The policy unique to a credential
store can then be updated as needed when credential libraries are added and
removed from the credential store.

#### Vault Boundary Controller Policy

The token Boundary receives must have the capabilities listed below. An explanation
for the use of each capability is given.

```hcl
# Allow Boundary to read and verify the properties of the token. This is
# provided by the "default" policy.
path "auth/token/lookup-self" {
  capabilities = ["read"]
}

# Allow Boundary to renew the token. This is provided by the "default"
# policy.
path "auth/token/renew-self" {
  capabilities = ["update"]
}

# Allow Boundary to revoke the token when the credential store is updated
# to use a new token or the credential store is deleted. This is provided
# by the "default" policy.
path "auth/token/revoke-self" {
  capabilities = ["update"]
}

# Allow Boundary to renew the credentials in active sessions. This is
# provided by the "default" policy.
path "sys/leases/renew" {
  capabilities = ["update"]
}

# Allow Boundary to revoke the credentials issued for a session when the
# session is terminated.
path "sys/leases/revoke" {
  capabilities = ["update"]
}

# Allow Boundary to read and verify the token's capabilities for each Vault
# path used by the credential store. This is provided by the "default"
# policy.
path "sys/capabilities-self" {
  capabilities = ["update"]
}
```

The above [`boundary-controller` policy](https://boundaryproject.io/data/vault/boundary-controller-policy.hcl) is
available for download. Below is an example of writing this policy to Vault:

```shell-session
# Download the policy
$ curl https://boundaryproject.io/data/vault/boundary-controller-policy.hcl -O -s -L

# Write the policy to Vault
$ vault policy write boundary-controller boundary-controller-policy.hcl
```

### Static Credential Store

A static credential store allows user-supplied credentials to be managed by Boundary. Credentials are encrypted and stored directly in Boundary. Currently, the static credential store can hold credentials of type `username_password`.

[token_requirements]: /boundary/docs/concepts/domain-model/credential-stores#vault-token-requirements
[token_policy]: /boundary/docs/concepts/domain-model/credential-stores#vault-boundary-controller-policy
[vault]: https://www.vaultproject.io/
[namespace]: /vault/docs/enterprise/namespaces
[renewable]: /vault/api-docs/auth/token#renewable-1
[periodic]: /vault/api-docs/auth/token#token_period
[orphan]: /vault/api-docs/auth/token#orphan
[PKI workers]: /boundary/docs/configuration/worker/pki-worker
[filter]: /boundary/docs/concepts/filtering/worker-tags
